// Copyright (c) Appeon. All rights reserved.
// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. 
// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.

namespace SnapObjects.Data
{
    /// <summary>
    ///     Represents an object used to cache the ISqlBuilder object.
    /// </summary>
    public interface ISqlBuilderCache
    {
        /// <summary>
        ///     Caches an ISqlBuilder object in the ISqlBuilderCache object and specifies a cache name for the ISqlBuilder object.
        ///     You can also specify whether the ISqlBuilder object is read-only when it is obtained from the cache; by default it is read-only.
        /// </summary>
        /// <param name="sqlBuilderName">The name for the ISqlBuilder when it is cached.</param>
        /// <param name="sqlBuilder">The ISqlBuilder object to be cached in the ISqlBuilderCache object.</param>
        /// <param name="readOnly">
        ///     Specifies whether the ISqlBuilder object is read-only when it is obtained from the cache. 
        ///     True(default) : you can only use the Get method to get an ISqlReadOnlyBuilder object from the cache. 
        ///     False: you can use the Get method to get an ISqlReadOnlyBuilder object from the cache or use the 
        ///     GetModifiable method to get a TSqlBuilder object.
        /// </param>
        void Set(string sqlBuilderName, ISqlBuilder sqlBuilder, bool readOnly = true);

        /// <summary>
        ///     Gets an ISqlReadOnlyBuilder object by the specified name.
        /// </summary>
        /// <param name="sqlBuilderName">The name for the ISqlBuilder object when it is cached.</param>
        /// <returns>
        ///     Returns an ISqlReadOnlyBuilder object by the specified name.
        /// </returns>
        ISqlReadOnlyBuilder Get(string sqlBuilderName);

        /// <summary>
        ///     Gets a modifiable TSqlBuilder object by the specified cache name.
        /// </summary>
        /// <typeparam name="TSqlBuilder">
        ///     The type of a derived interface of ISqlBuilder, such as ISqlQueryBuilder.
        /// </typeparam>
        /// <param name="sqlBuilderName">
        ///     The cache name for the ISqlBuilder object when it is cached.
        /// </param>
        /// <returns>
        ///     If the TSqlBuilder object is specified as read-only when cached, returns a TSqlBuilder object by the 
        ///     specified cache name; otherwise, throws an exception.
        /// </returns>
        TSqlBuilder GetModifiable<TSqlBuilder>(string sqlBuilderName) where TSqlBuilder : ISqlBuilder;
    }
}
